---
title: GitBook에서 마이그레이션
description: 기존 GitBook 프로젝트를 Astro로 마이그레이션하기 위한 팁
type: migration
stub: true
framework: GitBook
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[GitBook](https://gitbook.com)은 버전 제어 통합 및 사용자 정의 가능한 기능을 통해 공동 작업 방식으로 문서와 책을 작성하고 게시하기 위한 웹 기반 플랫폼입니다.

## GitBook과 Astro의 주요 유사점

GitBook과 Astro는 프로젝트 마이그레이션에 도움이 되는 몇 가지 유사점을 공유합니다.

- Astro와 GitBook 모두 [Markdown](/ko/guides/markdown-content/)을 지원합니다. GitBook의 Git Sync 기능을 활용하여 기존 문서를 모두 마이그레이션할 수 있습니다.

- Astro와 GitBook은 모두 [파일 기반 라우팅](/ko/guides/routing/) 형식을 사용합니다. 기존 콘텐츠에 Astro의 파일 구조를 사용하고 새 페이지를 추가하는 것이 친숙하게 느껴질 것입니다.

## GitBook과 Astro의 주요 차이점

GitBook 문서를 Astro로 마이그레이션하면 몇 가지 중요한 차이점을 발견할 수 있습니다.

- GitBook 사이트는 온라인 대시보드를 사용하여 편집됩니다. Astro에서는 [코드 편집기](/ko/editor-setup/) 및 개발 환경을 사용하여 사이트를 유지 관리합니다. 컴퓨터에서 로컬로 개발하거나 StackBlitz, CodeSandbox 또는 Gitpod와 같은 클라우드 편집기/개발 환경을 선택할 수 있습니다.

- GitBook은 콘텐츠를 데이터베이스에 저장합니다. Astro에서는 각 페이지의 콘텐츠에 대한 [프로젝트 디렉터리](/ko/basics/project-structure/)에 개별 파일 (일반적으로 Markdown 또는 MDX)이 있습니다. 또는 [콘텐츠용 CMS](/ko/guides/cms/)와 Astro를 사용하여 데이터를 가져와 표시할 수도 있습니다.

- GitBook은 콘텐츠를 위한 Markdown 위에 사용자 정의 구문을 사용합니다. Astro는 GitBook에서 사용하는 것과 유사한 구문을 제공하는 선택적 [Markdoc 통합](/ko/guides/integrations-guide/markdoc/)을 통해 Markdoc을 지원합니다.

## GitBook에서 Astro로 전환

GitBook 문서 사이트를 Astro로 변환하려면 공식 [Starlight 문서 테마 시작 템플릿](https://starlight.astro.build)으로 시작하거나 [테마 쇼케이스](https://astro.build/themes?search=&categories%5B%5D=docs)에서 더 많은 커뮤니티 문서 테마를 탐색하세요.

공식 스타터 중 하나를 사용하여 새로운 Astro 프로젝트를 시작하려면 `--template` 인수를 `create astro` 명령에 전달할 수 있습니다. 또는 [GitHub의 기존 Astro 저장소에서 새 프로젝트를 시작](/ko/install/auto/#시작-템플릿)할 수 있습니다.

  <PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm create astro@latest -- --template starlight
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm create astro@latest --template starlight
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn create astro --template starlight
    ```
    </Fragment>
  </PackageManagerTabs>

새로운 Astro 프로젝트가 생기면 기존 GitBook 콘텐츠를 새로운 Astro 프로젝트에 동기화할 수 있습니다. GitBook에는 GitBook 콘텐츠를 GitHub/GitLab 저장소에 자동으로 동기화하는 [Git Sync 기능](https://docs.gitbook.com/product-tour/git-sync)이 있습니다.

문서 템플릿의 콘텐츠 컬렉션에 직접 동기화하려면 `src/content/docs/en` 또는 `src/content/docs`를 프로젝트 디렉터리로 지정하세요.

:::caution
Git Sync를 활성화할 때 "**GitBook to GitHub**"를 우선 순위로 지정해야 합니다. 이렇게 하면 GitBook 콘텐츠가 GitHub 저장소에 동기화됩니다. 그렇지 않으면 기존 GitBook 콘텐츠를 덮어쓰게 됩니다.
:::

콘텐츠를 동기화하면 이제 Astro 저장소에 GitBook 콘텐츠 사본이 생성됩니다. 향후 GitBook과의 동기화를 방지하려면 git sync를 비활성화하세요.

이제 콘텐츠를 Astro 프로젝트로 마이그레이션했지만 즉시 사용할 수는 없습니다. Astro 사이트에서 이 콘텐츠를 사용하려면 GitBook의 구문을 Astro와 호환되는 형식으로 수동으로 변경하는 데 시간이 필요합니다.

- Astro의 [Markdoc 통합](/ko/guides/integrations-guide/markdoc/)에서는 파일 확장자가 `.mdoc`여야 합니다. 이는 `.mdx` 및 `.md`와 같은 다른 Markdown 확장과의 충돌을 피하기 위한 것입니다.
- GitBook 구문은 GitBook 파일에서 닫는 태그를 나타내는 `/` 접두사가 `end`로 대체되는 Markdoc과 다릅니다. 파일 전체에서 이 표기법을 업데이트해야 합니다.
- GitBook의 일부 기능은 사용자 정의 컴포넌트에 의존합니다. 이러한 컴포넌트는 Astro에 존재하지 않으며 [Markdoc의 구성 `tags` 속성](/ko/guides/integrations-guide/markdoc/#astro-컴포넌트를-markdoc-태그로-사용)을 통해 생성 및 프로젝트에 추가되거나 파일에서 제거되어야 합니다.

## 커뮤니티 자료

- 여러분의 자료를 추가하세요!
